Skip to content

Add posting index and covering index documentation#404

Open
nwoolmer wants to merge 5 commits intomainfrom
nw_index
Open

Add posting index and covering index documentation#404
nwoolmer wants to merge 5 commits intomainfrom
nw_index

Conversation

@nwoolmer
Copy link
Copy Markdown
Contributor

@nwoolmer nwoolmer commented Mar 31, 2026

Summary

  • Add new documentation page for posting index and covering index (posting-index.md)
  • Update existing index, CREATE TABLE, ALTER TABLE ADD INDEX, SHOW, schema design, and SQL optimizer hints docs with posting index syntax and examples
  • Add posting index entry to sidebar navigation

Updates since initial generation

  • All column types now supported in INCLUDE — UUID, LONG256, BINARY, DECIMAL128/256, and arrays all work
  • Encoding options — document POSTING DELTA and POSTING EF syntax variants
  • Designated timestamp auto-inclusion — the designated timestamp is automatically included in covering index when INCLUDE is present
  • Out-of-line syntax — document INDEX(col TYPE POSTING) alongside inline syntax
  • SHOW COLUMNS — add indexType and indexInclude columns to show.md and table_columns() in meta.md
  • SHOW CREATE TABLE — add example rendering posting index with INCLUDE
  • CAPACITY restriction — note across all pages that CAPACITY is bitmap-only
  • INCLUDE restrictions — inline syntax and ALTER TABLE only; cannot include the indexed column itself
  • Storage details — break down compression strategy per column type category (ALP, FoR, raw copy, var-width sidecar)

Test plan

  • Verify yarn build succeeds with no broken links
  • Review posting index page renders correctly
  • Check cross-links between index pages work
  • Verify SHOW COLUMNS output matches actual server output
  • Confirm SHOW CREATE TABLE example matches actual DDL rendering

🤖 Generated with Claude Code

New page: concepts/deep-dive/posting-index.md
- When to use, creating with INDEX TYPE POSTING and INCLUDE
- Covering index: how it works, supported types, choosing columns
- Verifying with EXPLAIN, comparison with bitmap index
- All accelerated query patterns with examples
- SQL optimizer hints (no_covering, no_index)
- Trade-offs: storage, write performance, memory
- Architecture: file types, generations, sealing, FSST compression
- Limitations

Updated pages:
- indexes.md: added index type comparison table
- create-table.md: added posting index and INCLUDE syntax
- alter-table-alter-column-add-index.md: added posting + INCLUDE examples
- sql-optimizer-hints.md: added no_covering and no_index hints
- schema-design-essentials.md: added indexing decision guide
- sidebars.js: added posting-index to Deep Dive navigation
@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 31, 2026

🚀 Build success!

Latest successful preview: https://preview-404--questdb-documentation.netlify.app/docs/

Commit SHA: e187aac

📦 Build generates a preview & updates link on each commit.

nwoolmer and others added 4 commits April 10, 2026 14:29
- All column types now supported in INCLUDE (UUID, LONG256, BINARY,
  DECIMAL128/256, arrays were added since initial docs)
- Document encoding options: POSTING DELTA and POSTING EF syntax
- Document designated timestamp auto-inclusion in covering index
- Add out-of-line INDEX(col TYPE POSTING) syntax examples
- Add SHOW COLUMNS indexType and indexInclude columns to show.md,
  meta.md (table_columns), and posting-index.md
- Add SHOW CREATE TABLE example with posting index
- Note CAPACITY restriction (bitmap only) across all relevant pages
- Note INCLUDE restrictions (inline syntax only, cannot include
  indexed column itself)
- Update storage/compression details per column type category

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- explain.md: add CoveringIndex and PostingIndex plan node descriptions
- symbol.md: add posting index example alongside bitmap in indexing section
- alter-mat-view-alter-column-add-index.md: add TYPE POSTING syntax
  (INCLUDE not supported on materialized views)
- _cairo.config.json: add cairo.posting.index.auto.include.timestamp and
  cairo.posting.index.row.id.encoding config keys; clarify bitmap-only
  scope of cairo.index.value.block.size and cairo.spin.lock.timeout

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Delta encoding compresses best for regular, evenly-distributed data and
is faster for large scans. The adaptive (default) mode additionally
trial-encodes a flat layout that compresses better for irregular
distributions and is faster for point queries.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- POSTING DELTA: regular data, better compression for even distributions,
  faster for large sequential scans
- POSTING EF: Elias-Fano encoding, better compression for irregular
  distributions, faster for point queries
- POSTING (default): adaptive, trial-encodes both per stride, picks smaller

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant